BlastDOS

home *** CD-ROM | disk | FTP | other *** search

/ BlastDOS / [DOS_Application]_BIT_Software_-_BitCom_3.58c_-_Distribution_Disks.zip / SCRIPT.TXT < prev next >

Wrap

Text File | 1989-10-09 | 94KB | 2,028 lines

1 Creating Script/Action Files Automatic Logon With Script/Action Files ---------------------------------------- If you call a certain number frequently, you will probably want to set up an automatic log on file so you don't always have to remember the correct log on sequence. This is done with BitCom's action files. The BitCom script and action file commands are similar to computer programming languages such as BASIC or macro commands in Lotus 1-2-3 or other programs. You do not need to use them to communicate using BitCom, but it will help you to work more efficiently. Script and action files are regular DOS text files that contain instructions that tell BitCom what to do. They are created, stored, and edited just like any other text files in DOS. There is no limit as to the number of lines a script or action file can contain. You can even call an action file from another action file. To create your own auto-log file (ACTION file), use any word processor or text editor capable of creating text files (such as PE, or EDLIN). If you use WordStar, or any program that includes formatting codes within the file, use the non- document (or ASCII) mode. Your ACTION file simply contains lines of instructions or statements that tell BitCom how to do an auto logon. Included on the program diskette are sample script and action files (which have a filename extension of .ACT or .SCP). These files can be printed using whatever method you normally use to print text files. Refer to the end of this section for a complete description of the script/action file commands. Creating and Using a Script/Action File --------------------------------------- To use a script/action file, you would go through the following steps. 1. Exit from BitCom. 2 2. Start your word processor. Instead of a word processor, you may also use EDLIN or any text editor. You should create a file without any formatting commands. The filename must have an extension of .ACT for an action file, or .SCP for a script file. You can edit any existing script or action file that we provide on the diskette. 3. Create and save the file. For example, you would type the lines shown in the example above to create a logon file for Easylink. Move the file to the BitCom sub- directory. 4. Bring up the BitCom Main Menu. Choose '1', Communications Selection Menu. Position the pointer next to the desired Record ID and press "S" to Show More. If you wish, you may instead add a record. 5. On the Communications Parameters Menu shown, under AUTOLOG FILE, type the name of the file that you created in step 3 above. The pathname may also be included if the file is not in the current path. For example: C:\WS\EASYLINK. The filename extension of .ACT should not be included. Sample Action Files ------------------- As a simple example, to send a RETURN (CR or Hex 0D) to the host computer, create the line: "$0D" To send a line feed (Hex 0A), create the line: "$0a" To send a string of characters, followed by a carriage return and line feed, create the line: "HELLO$0D$0A" In fact, you may send any combination of ASCII codes to the host by using the dollar sign ($) followed by a hex number, within quotes. Upper/lower case of hex numbers is irrelevant. The double quotes indicate that the text within them is to be sent through the COM port. Any characters between opened and closed braces '{}' will be treated as a comment, and ignored by BitCom. All comments must begin and end on the same line. 3 The following is a sample autolog file that is used to log on to the CompuServe service: {Autologon file for CompuServe Network} twait(1,"sec") {wait for 1 second} "$03" {send Ctl-C character hex 03} cwait("ID:") {wait until the host} {sends the 'ID' string } "xxxxx,yyy$0d" {send login ID} {followed by carriage return} {hex 0d return} cwait("word:") {wait for pass'word:'} {prompt} "xxxxx/yyyyy$0d" {send password} {followed by carriage return} invoke handykey {invoke another file} {which defines some keys} The general sequence as given above can be used for most services (i.e. wait for a string, send a response). The file 'HANDYKEY.ACT' defines the following keys. {This file defines some} {handy function keys} @alt-a='sendfile(prompt("Enter filename:"),"xmodem")' @alt-c='@a=prompt("Enter color code:");z#setatt(@a)' @alt-d='{Give DOS cmd}@a=prompt("Enter DOS cmd:");dos(@a)' @alt-e='{echo on} echo = 1;' @alt-n='{echo off} echo = 0;' @alt-t='{display time}typecr("Current time is @ctime")' @alt-h='{hangup phone} hangup; "ATH$0d"' @alt-x='@maxrow=44;dos("setmode -ammono -c132 -r44 - mmon");clear;z#setmar(1,44)' @alt-y='@maxrow=25;dos("setmode -ammono -c80 -r25 - mmon");clear' @alt-s='{let the host get a file} invoke sendfile.act' @alt-z='{Clear screen} clear' You can also create more complicated action files to prompt you for information, and operate differently depending upon the keys pressed or words received from the host computer. See the end of this section for more details. See below the action file which is on your program diskette. This is used to logon to the Easylink network. 4 cwait("ID?") "00 EIDxxxxx yyyyyyy$0d" {your own acct # and password} cwait("PTS") TYPE("PLEASE TURN ON PRINTER") cwait("PTS") {wait for Easylink ready again} printer(1) {print function on} "/MBX$0a" {read mailbox, print and capture} cwait("PTS") {wait for Easylink ready again} printer(0) {print function off} invoke handykey Another example is shown below. This is the sample action file used to log in to The Source. @RETURN;@RETURN CWAIT("=") "D1";@RETURN CWAIT("@@") "C xxxxx";@RETURN CWAIT(">") "ID yyyyyy";@RETURN CWAIT(":?"); "TEST";@RETURN; Replace the 'x' and 'y' characters with your own ID and password. The sample action file below is used to log on to Dow Jones News Retrieval through Tymnet. TWAIT(5,"SEC") {WAIT 5 SECONDS} "A" {SEND AN "a"} CWAIT("log in") {WAIT FOR "log in"} "DOW1;;" {SEND DOW1;} CWAIT("?") {WAIT FOR ?} "DJNS$0d" {SEND DJNS & CR} CWAIT("PASSWORD") {WAIT FOR PASSWORD} "xxxxxx$0d" {REPLACE x's WITH YOUR P/W} Run a Script File From DOS -------------------------- Script files can also be run from the DOS command line. This feature allows you to do unattended operations without having to go through the menus. The syntax to run a SCRIPT file from the DOS command line is: BITCOM @FILENAME.SCP [arg_1 arg_2...argn] where FILENAME is the name of the script file, and arg1...argn are optional arguments that can be included if they are required by the SCRIPT file. 5 For example, the SCRIPT file DIAL.SCP that is on your program diskette can be invoked from the DOS command line, or in a batch file as: BITCOM @DIAL.SCP EASYLINK MCI This line will start BitCom, invoke the SCRIPT file DIAL.SCP, using the arguments of EASYLINK and MCI, which are records in your phone number database. Note that you must include a space between BITCOM and the filename, and also between the filename and each argument. When you start BitCom and invoke a script file using this method, your script file must contain the CANCEL command to quit BitCom and return to DOS. In the example above, when the line is disconnected, BitCom will NOT return to DOS. Instead, the script file would be started over again, just as it did when you started it the first time. Script/Action File Syntax ------------------------- The following section presents the language rules (i.e. syntax and semantics), as well as the various procedures available for BitCom SCRIPT and ACTION files. If you are a beginner, we suggest that you look at the sample action files on the program diskette, and start with simple ones such as EASYLINK.ACT. There are two types of files in which language controls may be given. They are: 1. ACTION Files - These files have a filename extension of .ACT and may contain function key definitions and commands to control automatic logon or other common key sequences. ACTION files are invoked automatically to perform tasks after you have made a connection with the host computer. 2. SCRIPT Files - These files have a filename extension of .SCP and may contain commands to control when to call a certain number, how many times to retry, and what to do if the connection is (or is not) established. SCRIPT files are invoked to make a connection with the host computer. Note that when you use a Script file to make a connection, and an action file is specified on the Communication Parameters Menu, the Action file will be automatically invoked after the connection is made. Most commands used in a script file can also be used in an action file. Therefore, a script file can contain all the commands necessary for a communications session without having an action file. 6 These files can be created with any text editor capable of creating standard "text" files (e.g., PE or EDLIN). They CANNOT be created in BitCom. You can use your word processor if it can create text, or ASCII, files. The text in these files may consist of assignment statements, conditional statements, branching statements, and function calls. Comments may be placed anywhere in a file by surrounding the comment with opening and closing braces ('{' and '}'). Comments must always begin and end on the same line. Also, upper/lower case assignments are ignored (except for strings being sent to the host or typed at the terminal). For example, 'Bell' = 'BELL' = 'bell'. Normally, in your ACTION file, you will place each statement on a single line. However, you may place multiple statements on a single line by separating each statement with a semi-colon ';'. If you only have one command per line, the semi-colon at the end of each line is optional. Reserved Symbols ---------------- Certain symbols are reserved in BitCom as they have special meanings. If you wish to use any of these symbols in a text message, it is necessary to place two of them in a row. For example, if you wish to use the @ symbol in a message, you would use "@@". The symbols and their meanings are as follows: 7 Symbol Name Meaning ------ ---- ------- ; Semi-colon Ends one command and begins another $ Dollar sign Beginning of a hex value ( Open Beginning of an argument Parentheses ) Close Ending of an argument Parentheses \ Back slash Beginning of a decimal value @ At sign Beginning of a builtin variable = Equals Equal for comparison > Greater than Greater than for comparison < Less than Less than for comparison <> Not equal to Not equal to for comparison + Plus Addition * Asterisk Multiplication - Hyphen Subtraction " Double quote Beginning and ending of text (strings) ' Single quote Beginning and ending of the assignment of key variables { Open brace Beginning of comments } Closed brace Ending of comments 8 Variables --------- Variables are similar to a storage place, or cell, that is used in the BitCom language to store information. There are several types of variables which can be used in the BitCom language. "Scratch" variables may be assigned a value for later use. "Argument" variables contain the values of any arguments passed on to a command file. "Key" variables allow you to assign values to, as well as invoke files with, special keys. And "Builtin" variables allow you to set and query various BitCom values. All variables begin with the special character '@' followed by the name of the variable. Note that if you need to include the character '@' in a command file, you must do so with two @ characters together (i.e. @@). Scratch Variables ----------------- There are 26 scratch variables that can be used to contain work values. These variables are named @A through @Z. Scratch variables are useful for saving values, and then changing the value later in the file. Argument Variables ------------------ When a SCRIPT or ACTION file is invoked, arguments may be passed on to it. The argument may be referred to in the file with the names @1 through @9 which represents arguments 1 through 9. A maximum of 9 arguments may be contained within one file. You may NOT assign values to argument variables. These can be used whether you invoke the script file from DOS, or from the menu. Key Variables ------------- Key variables allow you to: 1) Assign functions such as SENDFILE to a key. 2) Assign an escape sequence to a key for terminal emulation. 3) Invoke another action file by pressing a key. 4) Assign a string of text to a key. Key variables are the names of the special keys on the keyboard. Every special key has a unique name, and a string may be assigned to those keys. That function would then be executed when the assigned key is pressed. 9 If a key variable is used by itself in a statement, BitCom will perform that function as if the key itself had been pressed. The valid key variables are: @F1 @Alt-A @Ctl-A @Alt-F1 @F2 @Alt-B @Ctl-B @Alt-F2 @F3 @Alt-C @Ctl-C @Alt-F3 @F4 @Alt-D @Ctl-D @Alt-F4 @F5 @Alt-E @Ctl-E @Alt-F5 @F6 @Alt-F @Ctl-F @Alt-F6 @F7 @Alt-G @Ctl-G @Alt-F7 @F8 @Alt-H @Ctl-H @Alt-F8 @F9 @Alt-I @Ctl-I @Alt-F9 @F10 @Alt-J @Ctl-J @Alt-F10 @Home @Alt-K @Ctl-K @Sft-F1 @End @Alt-L @Ctl-L @Sft-F2 @Break @Alt-M @Ctl-M @Sft-F3 @BS @Alt-N @Ctl-N @Sft-F4 @Rtab @Alt-O @Ctl-O @Sft-F5 @Lfeed @Alt-P @Ctl-P @Sft-F6 @Return @Alt-Q @Ctl-Q @Sft-F7 @PgUp @Alt-R @Ctl-R @Sft-F8 @PgDn @Alt-S @Ctl-S @Sft-F9 @Ins @Alt-T @Ctl-T @Sft-F10 @Del @Alt-U @Ctl-U @Ctl-F1 @Esc @Alt-V @Ctl-V @Ctl-F2 @LfArr @Alt-W @Ctl-W @Ctl-F3 @RiArr @Alt-X @Ctl-X @Ctl-F4 @UpArr @Alt-Y @Ctl-Y @Ctl-F5 @DnArr @Alt-Z @Ctl-Z @Ctl-F6 @Ltab @CtlHome @CtlEnd @Ctl-F7 @CtlPgUp @CtlPgDn @CtlLeft @Ctl-F8 @CtlRight @Ctlprt @Altdsh @Ctl-F9 @Alteq @Alt-1 @Alt-2 @Ctl-F10 @Alt-3 @Alt-4 @Alt-5 @Alt-6 @Alt-7 @Alt-8 @Alt-9 @Alt-0 10 Also, the following keys on the numeric keypad may be defined: @Ctlret Control Return @NL-0 Numeric Keypad 0 @NL-1 Numeric Keypad 1 @NL-2 Numeric Keypad 2 @NL-3 Numeric Keypad 3 @NL-4 Numeric Keypad 4 @NL-5 Numeric Keypad 5 @NL-6 Numeric Keypad 6 @NL-7 Numeric Keypad 7 @NL-8 Numeric Keypad 8 @NL-9 Numeric Keypad 9 @NL-Dsh Numeric Keypad - @NL-Pls Numeric Keypad + @NL-Dot Numeric Keypad . To assign a value to a key, you would give an assignment statement such as: @alt-S='"a string"'; The single quotes surrounding the text indicate that what is contained within them is assigned to the key variable in the statement. The double quotes indicate that the text within the quotes is a string that will be sent to the host computer. You may also invoke the key (as if you had pressed it at the keyboard) by giving the name of the key as a statement by itself, such as: @Return; If it is not in quotes, however, it will not be sent through the port. You cannot use a key variable to perform a function that it normally would manually. For instance, the special key to Print is <F4>. You would use the function PRINTER(1) to enable printing, rather than the key variable of @F4. Builtin Variables ----------------- There are other variables defined that allow you to inquire about, set and/or retrieve certain information from BitCom screens. These parameters are usually set on the BitCom menus, however, these variables allow you to see and set the various parameters in various screens without entering the menus. The variables are given here, along with the field type that each refers to, and a definition. 11 These variables can be combined inside a function. See the IF command later in this section as an example. Those variables with an asterisk next to their type may only be used in a script file, not an action file. Name Type Contents ---- ---- -------- @Autofil String Name of automatic logon file @Autolf Number Auto linefeed filter, 0=off, 1=on @Baud Number Current baud rate @Bell Number Current bell setting; 0=off, 1=short beep, 2=long beep, and 3=long warble @BlankLn Number Blank line filter, 0=off, 1=on @BreakT Number Number of hsecs that a break should last @Capmode Number Capture mode, 0=Replace, 1=Append @Capname String Name of capture file @Cdate String Current date shown in the format 'mm/dd/yy' @Col Number Current cursor column location @Comport String* COMM port, 1=COM1, 2=COM2, 3=COM3, 4=COM4 @Conn Number* Connection status, 0=not connected, 1=connected, 2=dialed line busy @Crec Number Current record number @Csend Number Character delay,1=wait for echo, 0=none, or number of hsecs to wait @Ctime String Current time shown in format 'hh:mm am/pm' @Data Number Number of data bits @Desc String Current record description @Dldir String Sub-directory that files will be down-loaded to. Shown as @DLDIR='name' where name is the sub-directory name @Echo Number 0=no echo, 1=echo on @Emulate Number Emulation file name, without extension @Exptab Number Expand tab filter; 0=off,1=on @Input Number Input filter, 0=off, 1=on @Ldate String Last connect date shown in the format 'mm/dd/yy' @Lsend Number Line delay, 2=manual, 1=wait for line feed, 0=none, or number of hsecs to wait 12 Name Type Contents ---- ---- -------- @Ltime String Last connect time shown in format 'hh:mm am/pm' @Maxrow Number The number of rows on your monitor, usually 25. If a graphics card is switched to 44 rows, must change @Maxrow to 44. @Mcol Number Maximum number of columns on the current screen @Mode Number* 0=Answer, 1=Dial @Mrow Number Maximum number of rows on the current window. Must be less than @Maxrow. @Note1 String First line of notes @Note2 String Second line of notes @Output Number Output filter, 0=off, 1=on @Parity String N=None, E=Even, O=Odd, M=Mark @Phone String Current phone number @Recid String Current record Id @Redial Number Number of seconds to wait between redials, shown in seconds @Row Number Current cursor row number @Stop Number Number of stop bits @Trace Number 0=trace off, 1=hex, 2=ASCII @Upcase Number Upper case filter, 0=off, 1=on Constants --------- Constants can be used to compare with and set variables. They can be either numbers or strings of characters (text). Numbers can be given as simple integers only, optionally preceded by a sign character. There are three types of strings that can be given: Those enclosed in double quotes (") Those enclosed in single quotes (') Those enclosed in no quotes at all. Strings enclosed in double quotes (called a d-string) must be preceded and followed by a double quote ("). To specify a string containing a double quote, therefore, you must specify two double quotes ("") in a row. 13 A string enclosed in single quotes (called an s-string) must be preceded and followed by a single quote. Again, to specify an s-string containing a single quote, specify two in a row. In a d-string, if a variable name is found in the string (e.g. @1) the variable will be substituted with its value. Text which is enclosed in double quotes will be sent to the host computer. If you wish to immediately follow a variable with a non-blank character, you must follow the name of the variable with a period. That period will be stripped off of the resulting string. Thus, if @a has been assigned the value "def", as in the example: @a = "def" then: "@a" is "def" "abc@a" is "abcdef" "abc@a.ghi" is "abcdefghi" Note that if a d-string contains a variable name for which no value has been defined, the variable will be substituted with a null string. No error message will be displayed. To include an at-sign (@) in a d-string, specify two @'s in a row (e.g. @@). A d-string may also contain the hexadecimal representation of a character. This is often useful when sending special characters to the host computer, or when searching for a special character. Specify the hexadecimal character as "$xx" where the 'xx' is in the range of 0-9 and A-FF. For example, the line feed character would be shown as "$0A". As usual, specify two $'s in a row to actually include a dollar sign ($) in a string. With an s-string, no variable substitution will take place. This is useful when assigning strings to function keys for later evaluation. Examples of valid constants are: "This is a d-string" "This is a d-string with a double quote ("") in it" 'This is an s-string with a double quote (") and single quote ('')' Also, if you wish to give a string containing no blanks in it, you may omit the quotes (i.e. specifying "ABC" is the same as ABC). 14 Statements ---------- BitCom uses four types of statements. They are variable statements, assignment statements, procedure calls, and control statements. Statements may be separated with a semi-colon (;) to place more than one statement on a line. The semi-colon is optional if the line only contains one command. Variable Statements ------------------- A variable statement consists of one of the following: 1. The name of a variable (e.g. @1 or @a) 2. A constant string or numeric value 3. The name of a key variable In the first two instances, the resulting string of the variable constant is SENT to the communications port as though you had typed the string at the keyboard. If the variable had contained a numeric value, the string that would represent the number is sent (i.e. 200 = "200"). In the third case shown above, if a key variable is given, then the action will be taken if an ACTION string has been assigned to that key. Otherwise the value of the key will be sent to the communications port as though you had pressed that key at the keyboard. Note, however, that the special keys (Help, Confirm, etc.) cannot be invoked this way. For example, "logid";@return; {sends "logid" followed by carriage return} @a; {sends keystrokes defined in string assigned} @1; {sends string in argument 1} Assignment Statements --------------------- An assignment statement is used to assign a value to a variable. It would look like this: variable = value; The variable may be any valid builtin function described earlier in this chapter. The value may be either a number, a d-string, an s-string, another variable name, or a function name. Examples of valid assignments are: @baud=1200 @Note1="We tried to connect at @Cdate"; @Alt-s='sendfile("prompt("Send File Name?")","Xmodem")' 15 Note that the last example defines the @Alt-S key to prompt for a filename, and then begin sending that file. Function Calls -------------- There are many BitCom functions which may be invoked to perform a variety of tasks. These functions are invoked by giving the function name. Some functions are not conditional, and therefore do not require any arguments. Any arguments the function does require must be enclosed in the left and right parenthesis and separated by commas. These functions always return a value which is either the result of the function or a return code indicating the success or failure of the task. These functions will be described in detail later in this section. The next section will provide you with detailed information of the functions available in the BitCom program language. As explained earlier, BitCom uses constants, variables, and statements to perform functions that you frequently use. BitCom script commands can be written using any word processor that creates text files. If you are not sure if your word processor does this, create a sample file. From the DOS prompt, use the TYPE command to display the file. You should only see the text that you have typed in. You should not see strange looking or graphics characters. A BitCom program CANNOT be written while using BitCom. You must use a word processor or text editor. The functions explained in this section can be used for terminal emulation, as well as SCRIPT and ACTION files. Upper/lower case of the functions and commands is insignificant in setting up these files. That is, whether you type commands in upper or lower case has no effect on the command itself. However, case is important when waiting for a particular string, such as in the CWAIT function. The functions in this chapter are arranged alphabetically. With each function, there will be five parts: the function name, the type of function, the syntax that should be used, the purpose for the function, and an example of how it is used. The following is a list of commands arranged according to their function. 16 Conditional String Handling File Handling ----------- --------------- ------------- IF CONCAT CAPTURE ELSE SUBSTR Branching Port I/O Miscellaneous --------- -------- ------------- ABORT EXIST BELL CANCEL GETCH DOS EXIT GETCHW EXPR GOTO GETLINE PRINTER INVOKE SBREAK PROMPT TRACE Display I/O File Transfer Event Wait ----------- ------------- ---------- CLEAR BPLUS CWAIT CLOCK KEREND TWAIT CURSIZE KERGET WAIT HELPLINE KERRECV WWAIT MESSAGE KERSEND POSCUR RECVFILE Flags & Switches SETCOLOR SENDFILE ---------------- TYPE CHRMAP TYPECR Connection ---------- DOCOMM HANGUP SELECT 17 FUNCTION: ABORT TYPE: BRANCHING SYNTAX: ABORT PURPOSE: This function will stop all processing, and exit BitCom to DOS. It will leave the line connected, allowing you to use other programs that talk to the modem. This is helpful if you have another program, such as a database that you use to communicate after you are connected, and you are only using BitCom to make the connection. EXAMPLE: In this example, you would exit BitCom, leaving the line connected, after a connection has been established. SELECT("EASYLINK") DOCOMM :LOOP IF (@CONN=1) GOTO :DONE TWAIT(2,"SEC") GOTO :LOOP :DONE ABORT ____________________________________________________________ FUNCTION: BELL TYPE: MISCELLANEOUS I/O SYNTAX: BELL PURPOSE: This function is used to sound the speaker (depending upon the current bell setting). This function can be used in SCRIPT or ACTION files, and will always return a zero. EXAMPLE: In the SCRIPT file DIAL.SCP, the label :didit shows: @bell = 3; {set bell sound to long warble} bell; {beep the speaker} @bell = 1; {set bell sound to short beep} In the following example, the bell will be sounded after a file is received. RECVFILE("PROMPT("ENTER FILE NAME")","XMODEM") BELL 18 FUNCTION: BPLUS TYPE: FILE TRANSFER SYNTAX: BPLUS("SEND") BPLUS("RECEIVE") PURPOSE: This function is used to send or receive files using the CompuServe B+ protocol. The filename is not necessary, as it is picked up from the host computer. EXAMPLE: In this example, you would receive a file using the CompuServe B+ protocol. BPLUS("RECEIVE") ____________________________________________________________ FUNCTION: CANCEL TYPE: BRANCHING SYNTAX: CANCEL[(MESSAGE)] PURPOSE: To cancel the processing of all command files and return to the keyboard state. The message argument is optional. It can be a string or a variable name. If the message is included, it will be shown on your screen when the system is returned to the keyboard state. EXAMPLE: In this example, if a file was not found, the processing of the command file will stop and you will be returned to the normal keyboard state. IF (EXIST("COMMAND.COM")=0) GOTO :BADFILE :BADFILE "File Not Found$0d$0a"; cancel Note that the CANCEL command does not stop or exit BitCom, but merely stops the processing of the SCRIPT/ACTION file. 19 FUNCTION: CAPTURE TYPE: FILE HANDLING SYNTAX: CAPTURE(1) CAPTURE(0) PURPOSE: This function will begin or end the capturing of a file during communications. Capture(1) will begin the capturing of a file, while Capture(0) will end the capturing of the file. EXAMPLE: This example will begin the capturing of a file after a connection is made. IF(@CONN=1) CAPTURE(1) The following example will stop capturing after "PTS" is received. CWAIT("PTS") CAPTURE(0) Note that the Communications Parameters Menu must contain a Capture Filename when you begin communications. ____________________________________________________________ FUNCTION: CHRMAP TYPE: FLAGS AND SWITCHES SYNTAX: CHRMAP(0) CHRMAP(1) PURPOSE: This command enables/disables character filtering and emulation. Character filtering tells BitCom to ignore and discard control characters when they are received from the host. CHRMAP(0) disables the character filtering and emulation, while CHRMAP(1) enables character filtering. If you are using terminal emulation, character filtering will be enabled and the INBUFFER section of the emulation file determines which characters are to be filtered and translated. By using CHRMAP(0), you can temporarily disable emulation and allow all control characters to be displayed on the screen. They will also be echoed to the printer if the print function is on. This function is especially useful if you want to print a formatted file while receiving it from the host computer. 20 EXAMPLE: CHRMAP(0) {DISABLED} CHRMAP(1) {ENABLED} Note: After you have disabled the character map filtering, make sure that you enable it again so that your terminal emulation will work correctly. ____________________________________________________________ FUNCTION: CLEAR TYPE: DISPLAY I/O SYNTAX: CLEAR PURPOSE: This function is used to clear the display screen on your PC (but not on the remote PC). EXAMPLE: This statement will assign the function of 'clear' to the key variable of @alt-z. When ALT-Z is pressed, the screen will clear. @ALT-Z = '{Clear Screen} clear' See also the command SETCOLOR. ____________________________________________________________ FUNCTION: CLOCK TYPE: DISPLAY I/O SYNTAX: CLOCK(0) CLOCK(1) PURPOSE: This function is used to turn the Connect clock display on or off. The Connect clock is displayed in the lower right corner of the screen. Normally, the display will be on after the "CONNECT" message is received from the modem. EXAMPLE: This example will assign the functions of turning the connect clock display on and off to function keys. @Alt-F1='CLOCK(1) {TURN CLOCK ON} @Alt-F2='CLOCK(0) {TURN CLOCK OFF} 21 FUNCTION: CONCAT TYPE: STRING HANDLING SYNTAX: CONCAT(arg1,arg2) PURPOSE: Used to concatenate argument 2 to argument 1 and return the result. EXAMPLE: @R = concat(@a,@b) The string in variable @b is appended to the string in variable @a. The result will be stored in @R. If @a is "How are you" and @b is "today", then @R will contain the string "How are you today." ____________________________________________________________ FUNCTION: CURSIZE TYPE: DISPLAY I/O SYNTAX: CURSIZE(start_line,end_line) PURPOSE: This function is used to change the size of the cursor according to the arguments of start_line and end_line. The IBM PC cursor is made up of scan lines from 1 to 10, depending upon the graphics card being used. Normally, Hercules and compatible cards have scan lines from 1 to 13, CGA cards have from 1 to 7, and EGA cards have from 1 to 8. The start_line argument is the top scan line of the cursor. The end_line argument is the last scan line of the cursor. If the start_line argument is greater than the end_line argument, the cursor will be turned off, and not visible on the display. EXAMPLE: For example, the following are various size cursors that can be used with an EGA monitor. CURSIZE(0,8) {FULL SIZE CURSOR} CURSIZE(4,8) {HALF SQUARE SIZE} CURSIZE(7,8) {NORMAL CURSOR} CURSIZE(9,9) {TURN OFF CURSOR} 22 You can also assign the cursor size to a key, so that it can be changed while you are connected. For example, the following lines can be added to your script or action file. @alt-f='cursize(0,8)'{full size, EGA monitor} @alt-m='cursize(3,8)'{half size, EGA monitor} @alt-n='cursize(7,8)'{normal, EGA monitor} @alt-o='cursize(9,9)'{turn off EGA cursor} @alt-l='cursize(1,13)'{full size, mono monitor} @alt-p='cursize(6,13)'{half size, mono monitor} @alt-q='cursize(12,13)'{normal, mono monitor} @alt-u='cursize(32,13)'{turn off mono cursor} ____________________________________________________________ FUNCTION: CWAIT TYPE: EVENT WAIT SYNTAX: CWAIT(string) PURPOSE: This function is used to wait for the given string from the host. It will always return a zero. If the given string is never matched, BitCom will continue to wait until you press the "Halt" key. EXAMPLE: If you want to wait for a prompt of a question mark (?) this can be done with the statement: CWAIT("?"); CWAIT("PLEASE LOG ON") Note: The string can be anywhere within a line or lines. It is suggested that you find a unique phrase or string to wait for. The string that this function waits for must match the string sent from the host computer exactly. It is case sensitive. For example "log on" and "LOG ON" are not the same string. ____________________________________________________________ FUNCTION: DOCOMM TYPE: CONNECTION SYNTAX: DOCOMM PURPOSE: This function will begin communications, using the current value of @MODE. If @MODE=0, the system is set up for auto answer. If @MODE=1, the current number shown in @PHONE will be dialed. If @MODE=2, it is assumed that there is a direct connection (i.e. not through a modem). This function can only be used in a script file. It cannot be used until the SELECT function has been used, nor can it be used in an action file. 23 EXAMPLE: The following example selects a record (EASYLINK), dials the number and checks for a connection. The loop testing for a valid connection must always be used after the DOCOMM function. SELECT("EASYLINK") DOCOMM :LOOP IF(@CONN=1)GOTO :DONE TWAIT(2,"SEC") GOTO :LOOP :DONE The DOCOMM command will return to the next line of the script file immediately. You must use the "IF" statement to check if the line has connected as shown in the example above. The loop must contain the two second TWAIT statement to give the modem time to connect. The DOCOMM command functions as if you were pressing the CONFIRM key while at the Communications Selection Menu. ____________________________________________________________ FUNCTION: DOS TYPE: MISCELLANEOUS SYNTAX: DOS(string) PURPOSE: This function will issue the given string as a DOS command. It will always return a zero. 24 EXAMPLE: This example will issue the SETMODE command as a DOS command to change the display to a 132 column by 44 row display, and assign these functions to the key variable of @ALT-X. @ALT-X='{132 mode} dos("setmode -ammono -C132 -44 -mmon")' The following example will invoke the DOS file COMMAND.COM and give you the real DOS prompt. To return to BitCom, you would type: EXIT and then press <ENTER>. DOS("COMMAND.COM") Also, you may put more than one DOS command together by the use of the pound sign (#). For example: DOS("DIR#PAUSE") This would first run a directory and then pause until you press a key before returning you to the communications screen. ____________________________________________________________ FUNCTION: ELSE TYPE: MISCELLANEOUS SYNTAX: See IF command for details ____________________________________________________________ FUNCTION: EXIST TYPE: PORT I/O SYNTAX: EXIST(filename) PURPOSE: This function is used to see if a filename exists on the disk. If the file does exist, the function will return a 1. If the file does not exist, the function will return a 0. The filename argument cannot contain wild card characters. 25 EXAMPLE: In this example taken from the file ANSWER.ACT, the line that is typed is a filename which is then assigned to the scratch variable @a. The next line checks to see if the filename exists with the EXIST function. @a = getline @b = exist(@a) if (@b=0) "File Does Not Exist" The following line shows that if the file does exist, to go to the label :DOIT IF (exist("LOTUS.DAT")=1) GOTO :DOIT ____________________________________________________________ FUNCTION: EXIT TYPE: BRANCHING SYNTAX: EXIT [message] PURPOSE: This function is used to stop all processing of the command file, and the system will be returned to the next highest level. If the script file was started at the DOS prompt, the EXIT command will exit BitCom to DOS. The "message" argument is optional. If given, it will appear on the screen after the command file processing is stopped. The message may be either a string or a variable name. This command is similar to the RETURN command in PASCAL or the RETSUB command in BASIC. EXAMPLE: In the sample file ANSWER.ACT, processing of the command file will be stopeed if a proper filename is not found. The system will be returned to the level the action file was started from. :badfile "File Not Found$0d$0a"; exit 26 FUNCTION: EXPR TYPE: MISCELLANEOUS SYNTAX: EXPR(expression) PURPOSE: This function will evaluate the given expression and return its value. The expression may consist of constants, variables or function calls separated by operators. Valid operators are: + Addition - Subtraction * Multiplication / Division Multiplication and division are performed before addition or subtraction, but the order of calculation may be controlled by the use of parentheses. EXAMPLE: In this example, the scratch variable @c is assigned to the expression of @c plus one. @c = expr(@c + 1); The following example will calculate 2 + 2 and display the result of 4 on the screen. We suggest that you put a space before and after any operator. TYPE(EXPR(2 + 2)) ____________________________________________________________ FUNCTION: GETCH TYPE: PORT I/O SYNTAX: @a = GETCH PURPOSE: This function will read a character that is received from the port. If a character is not available, it will return a -1. If a character is available, it will return that character. EXAMPLE: :loop IF (getch = -1) goto :loop The above 2 lines would wait until a character is received from the host. If a character is not received, it will go back and wait again. 27 FUNCTION: GETCHW TYPE: PORT I/O SYNTAX: @a = GETCHW PURPOSE: This function will read a character that is returned from the host computer. If none is available, it will wait for one. It will always return the character that is read. EXAMPLE: This example would tell the host to hit a key, and then wait until it does. "Press any key to continue" getchw ____________________________________________________________ FUNCTION: GETLINE TYPE: PORT I/O SYNTAX: @a = GETLINE PURPOSE: This function is used to get a line of text that ends with a carriage return or line feed from the host computer. EXAMPLE: As shown in the file ANSWER.ACT, the following lines make use of the function GETLINE. "ENTER PASSWORD:" {get password} @a=getline This will get a line of text and assign it to the scratch variable of @a for later processing within the file. ____________________________________________________________ FUNCTION: GOTO TYPE: BRANCHING SYNTAX: GOTO :label; PURPOSE: This function is used to cause processing to continue at the line beginning with the given label name. EXAMPLE: In this example, if the file "HELLO" exists, processing will begin at the label of :OK. IF (exist("HELLO")=1) goto :OK :OK 28 FUNCTION: HANGUP TYPE: CONNECTION SYNTAX: HANGUP PURPOSE: This function transmits the currently defined hangup string to the modem. The currently defined hangup string can be shown with the @HANGUP function. After the hangup command is executed, BitCom will return either to the menu the session was started from, or to DOS if BitCom was started from the DOS command line. If you have started the script file from the DOS prompt, the file will be invoked again when you use the HANGUP command, unless it is followed by the CANCEL command. EXAMPLE: In this example, if too many tries for a password are made, the hangup function will be invoked to hang up the phone. "Too many attempts..." hangup exit Be sure to use the EXIT command after HANGUP to stop the processing of the script file. Another example is to assign the HANGUP function to a function key, so that when the key is pressed, BitCom will hangup and return to the previous state. @ALT-H = 'hangup' 29 FUNCTION: HELPLINE TYPE: DISPLAY I/O SYNTAX: HELPLINE("MSG1 KEY1;....MSGX KEYX") PURPOSE: This function is used to replace the default help messages that appears on the lower left corner of your screen during communications with your own help messages. The default help messages are: HELP F1 OPTIONS F2 The "message" argument is your own message that will apply to a certain key that is specified in the "key" argument. Note that the message argument must not contain any spaces. EXAMPLE: The following example will show that CAPTURE can be turned off with the F9 key. HELPLINE("CAPTOFF F9; HELP F1") ____________________________________________________________ FUNCTION: IF TYPE: CONDITIONAL SYNTAX: IF (condition) statement 1; else statement 2 PURPOSE: The IF statement is used to test for a condition. If true, the remainder of the statements on the line are executed. Otherwise, the statements are skipped. A condition may consist of comparison operators, with AND and OR operators. Parentheses may be used to control the order of comparison. Valid comparison operators are: = Test for equality <> Test for inequality > Test for greater than < Test for less than >= Test for greater than or equal to <= Test for less than or equal to EXAMPLE: IF (@a=":") goto :gotcolon If the contents of @a are a colon, BitCom will go to the label :gotcolon. :loop1 @a=getchw if((@a<>":") and (@a<>"?")) goto :loop1 30 If the character received by the getchw command is not a colon or a question mark, BitCom will return to the label of :loop1. IF (@echo=0) type("ECHO OFF");ELSE type("ECHO ON") In this example, if @echo is equal to 0, the first statement would be typed. If @echo is equal to anything else, the second statement would be typed. ____________________________________________________________ FUNCTION: INVOKE TYPE: BRANCHING SYNTAX: INVOKE filename [arg1...arg9]; PURPOSE: This function is used to begin execution of another command file. This is similar to a sub- routine call in BASIC or other programming languages. EXAMPLE: In this example, from the file EASYLINK.ACT, the last line of the file will invoke HANDYKEY.ACT, another action file on the program diskette. invoke handykey ____________________________________________________________ FUNCTION: KEREND TYPE: FILE TRANSFER SYNTAX: KEREND("opt") PURPOSE: This Kermit function terminates the interaction with a Kermit server. If "opt" = "finish", it tells the server to exit. If "opt" = "logout", it tells the server to exit AND to disconnect the line. EXAMPLE: KEREND("finish") {tells the server to exit,} {but stay connected.} 31 FUNCTION: KERGET TYPE: FILE TRANSFER SYNTAX: KERGET("filename"[,"recvfilename"]) PURPOSE: This Kermit function requests that the host send the given filename. The host must be in the server mode before issuing this command. The first file sent will be placed in the receive filename, if one is given. EXAMPLE: KERGET("test.doc","test1.doc") This will request that the server send the file TEST.DOC, and save it to the receiving side under the filename TEST1.DOC. ____________________________________________________________ FUNCTION: KERRECV TYPE: FILE TRANSFER SYNTAX: KERRECV PURPOSE: This Kermit function begins waiting for one or more files to be sent from the host using the Kermit protocol. The receive filename should be omitted. The filename can include a path. If the transaction is successful, it will return a zero. If it was unsuccessful, it will return a -1. EXAMPLE: KERRRECV This example will receive files into the current directory (or the directory specified in @DLDIR) using the Kermit protocol. The file names will be created by the sending computer. ____________________________________________________________ FUNCTION: KERSEND TYPE: FILE TRANSFER SYNTAX: KERSEND("filename") PURPOSE: This Kermit function will send one or more files to the host using the Kermit protocol. The host must already be in the Kermit receive mode, or the Kermit server mode. This function will return a - 1 if it was unsuccessful, and a zero if it was successful. EXAMPLE: KERSEND("test1.doc") This line will send the file TEST1.DOC, using the Kermit protocol. 32 FUNCTION: MESSAGE TYPE: DISPLAY I/O SYNTAX: MESSAGE(string) PURPOSE: This function is used to display the given string in the message area of the display (lower right corner of the screen). This function will always return a zero. EXAMPLE: In the emulation file VT100A.EMU, if certain characters are received, you will be prompted to use the emulation file VT100B.EMU as shown below. [?21 message("Received VT52 sequence. Use VT100B.EMU"); ____________________________________________________________ FUNCTION: POSCUR TYPE: DISPLAY I/O SYNTAX: POSCUR(col,row) PURPOSE: This function is used to move the current cursor position to a specific column and row. The valid ranges are: col = 1 - 80 (or 132) row = 1 - 24 (or any number defined in the @MAXROW variable within an action file) This function will always return a zero. EXAMPLE: This statement will set the cursor position at column 1 and row 1. poscur(1,1) ____________________________________________________________ FUNCTION: PRINTER TYPE: MISCELLANEOUS SYNTAX: PRINTER(1) PRINTER(0) PURPOSE: This function is used to enable or disable the printer logging on and off. PRINTER(1) enables the print function. Everything appearing on the screen after this command would be echoed to the printer. PRINTER(0) will disable the print function. Make sure that your printer is connected and on- line when using this function. 33 EXAMPLE: In this file, the print function will be enabled; files will be read, and then the print function will be disabled. This example is from the file EASYLINK.ACT. printer(1) {print function on} "/READALL$0a" {read message, print & capture data} cwait("PTS") {wait for easylink ready again} printer(0) {print function off} ____________________________________________________________ FUNCTION: PROMPT TYPE: DISPLAY I/O SYNTAX: PROMPT(string) PURPOSE: This function will type the given string on the display (without a carriage return), and then read from the keyboard until the carriage return key is pressed. The string that is entered will be returned. Note that the prompt is only sent to your display, and not to the host computer. EXAMPLE: In this example, the prompt shown in parentheses is assigned to the scratch variable @b. @b=prompt("Enter X for XMODEM, A for ASCII:"); The following example shows you how to combine the SENDFILE function with the PROMPT function. @alt-s='SENDFILE("PROMPT("SEND FILENAME?")","XMODEM")' ____________________________________________________________ FUNCTION: RECVFILE TYPE: FILE TRANSFER SYNTAX: RECVFILE(filename,mode [eof]) PURPOSE: This function initiates a file receive. The variable 'filename' is the name you will receive the file under. The 'mode' may be either XMODEM or ASCII. If the mode is ASCII, you may also give the string to indicate the end-of-file has been reached. If this argument is omitted, Ctrl-Z (Hex 1A) will be taken as the end-of-file character. When using the Kermit protocol, use the KERRECV function instead. 34 You can use this command to receive files under the YMODEM protocol, by using wild card characters in the filename, such as: RECVFILE("*.*","XMODEM") EXAMPLE: The following example is the last line of the sample ACTION file RECFILE.ACT which is on your program diskette. The scratch variable @a was previously assigned the value of a given filename. @A = prompt("ENTER FILE NAME"); RECVFILE("@a","ASCII","$07"); Note that in the above example, the end-of-file mark has been changed to Hex 7. ____________________________________________________________ FUNCTION: SBREAK TYPE: PORT I/O SYNTAX: SBREAK PURPOSE: This function is used to send a break signal to the host computer. This performs as if you had pressed the BREAK key that was defined on your Communication Parameters Menu. EXAMPLE: In this example, the system would wait 2 seconds, and then send a break signal to the host. TWAIT(2,"SEC") SBREAK ____________________________________________________________ FUNCTION: SELECT TYPE: CONNECTION SYNTAX: SELECT (Rec_ID) PURPOSE: This function will select the given Record ID for later use with the DOCOMM function. It is used in SCRIPT files. The Record ID must have been previously defined, either through builtin variables, or the Communications Parameters Menu. The running of the SCRIPT file will be cancelled if the given Record ID is not found. 35 EXAMPLE: This example will select the "EASYLINK" record and dial the phone number contained in that record. SELECT(EASYLINK) DOCOMM Note: Selecting a record will change the parameter settings such as parity, stop bits, emulation filename, and capture filename. You can select a different record while online. This is useful in assigning a different capture file when you switch to another session. ____________________________________________________________ FUNCTION: SENDFILE TYPE: FILE TRANSFER SYNTAX: SENDFILE(filename,mode) PURPOSE: This function initiates a file send. It may only be used after a connection has been established. It has two arguments which must be defined. The filename is the name of the file which will be sent, and the mode may either be XMODEM or ASCII. When using the Kermit protocol, use the KERSEND function instead. This function will return a zero if it was successful, and a -1 if it was unsuccessful. EXAMPLE: This example will send the file "BITCOM.EXE" using the XMODEM protocol. SENDFILE("BITCOM.EXE","XMODEM") ____________________________________________________________ FUNCTION: SETCOLOR TYPE: DISPLAY I/O SYNTAX: SETCOLOR(m) PURPOSE: This function will set the initial screen color to the value of 'm'. When the CLEAR command is later used, the screen will be cleared, and the color set to the value of 'm'. Refer to the file REFER.TXT for color codes. The default color is white characters on a blue background. The value of 'm' is a shown in decimal form. EXAMPLE: SETCOLOR(23){blue background, white characters} CLEAR Note that the CLEAR function must follow the SETCOLOR command for the screen attributes to change. 36 FUNCTION: SUBSTR TYPE: STRING HANDLING SYNTAX: SUBSTR(string,start,len) PURPOSE: This function returns a set of characters which is a sub-set of a given string. "String" is a given string that you supply. "Start" is the starting character position in the string. "Len" is the number of characters returned. Note that "String" can be a variable argument or a string constant. EXAMPLE: One example is shown here. This is from the sample action file ANSWER.ACT, which is on your program diskette. @a=getline if (substr(@a,1,8) <> "JONATHAN")goto :badpw goto :ok This will return a sub-string of the given string, starting at character '1' (where J is the first character). The string will be '8' characters long. The 'len' argument may be omitted, in which case the sub-string will be from the 'start' till the end of the 'string'. ____________________________________________________________ FUNCTION: TRACE TYPE: MISCELLANEOUS SYNTAX: TRACE(1) TRACE(0) PURPOSE: This function is used to enable/disable the tracing of the currently running SCRIPT/ACTION file. TRACE(1) begins tracing. TRACE(0) disables tracing (this is the default setting). This function will always return a zero. EXAMPLE: Trace(1) at the beginning of a script or action file will trace (show on the screen) the file as it is being executed. After trace is enabled, BitCom will display each line of the file that it is executing, and the result. This is not the same as the Trace filter on the Communications Parameters Menu. TRACE(1) {Begin tracing action file} 37 FUNCTION: TWAIT TYPE: EVENT WAIT SYNTAX: TWAIT(time,"unit") PURPOSE: This function is used to wait for a given period of time, shown in the given unit. Valid units are: hsec hundredths of seconds sec seconds min minutes hour hours This function will always return a zero. While you are waiting, any characters received from the communications port will be passed on to the display. EXAMPLE: The following command will delay two seconds before continuing with the processing of the file. TWAIT(2,"sec") {wait 2 seconds} ____________________________________________________________ FUNCTION: TYPE TYPE: DISPLAY I/O SYNTAX: TYPE(string) PURPOSE: This function will type the given string at the display. No carriage return will be entered. This function will always return a zero. EXAMPLE: Following are some examples of the TYPE function. TYPE("PLEASE TURN ON THE PRINTER"); TYPE("The echo mode is @mode"); TYPE("The current window size is @mrow line"); IF (@echo=1) TYPE("ECHO IS ON"); Note that the string will only be shown on your display, and not sent through the communications port. 38 FUNCTION: TYPECR TYPE: DISPLAY I/O SYNTAX: TYPECR(string) PURPOSE: This function will type the given string at the display, and end the string with a carriage return. This function will always return a zero. This function works exactly like TYPE except that the cursor is brought to a new line after the message is displayed. EXAMPLE: In this example, a line of text will be typed on the display. The cursor will then move down one line. typecr("LOGON OK"); Note that the string will only be shown on your display, and not sent through the communications port. ____________________________________________________________ FUNCTION: WAIT TYPE: EVENT WAIT SYNTAX: WAIT(hour,min) PURPOSE: This function is used to wait until the given hour and minute occurs. The hour must be given in 24 hour time. The wait will occur until the next occurrence of the given time. This function will always return a zero. Note that while you are waiting, any characters received from the communications port will be passed on to the display. EXAMPLE: Following is an example in which the WAIT function is used. WAIT(23,59) {WAIT UNTIL 11:59 PM} 39 FUNCTION: WWAIT TYPE: EVENT WAIT SYNTAX: WWAIT(time) PURPOSE: This function is used to wait until there are no characters received on the line for the number of seconds shown in 'time'. This is useful to determine when the host is prompting you for some input. If you are unsure what the prompt will be, you can check the last word in the prompt and respond accordingly. EXAMPLE: wwait(30){wait for 30 seconds if nothing received} This example will simply wait for 30 seconds if nothing is received on the line. @a=wwait(2) if(@a="name?") goto :cont; The above example will wait for the string 'name'. If not received within 2 seconds, processing will continue. If the string "name" is received, it will go to the label of :cont.